JMU JMU - Department of Computer Science
Help Tools
The CS159 Style Guide for Java


Your Java code must comply with the CS159 Style Guide for Java. Note that the examples discussed in the lectures, labs, and readings may not comply with these guidelines as they were prepared by different people and at different times.

1 Terminology

The word "must" indicates that the guideline is mandatory. The word "should" indicates that the guideline is not mandatory but is strongly recommended. The word "may" indicates that the guideline is an exception to another guideline and should be applied rarely.

Some of the guidelines are of the kind that are used by programming professionals. Others are of the kind that are appropriate for beginning programmers (because they improve understanding) but that are less important for professionals.

2 The Guide

2.1 Organization/Structure

  1. Each class must be in its own file.

    The name of the file and the name of the class must coincide exactly. For example the Queue class must be in a file named Queue.java. Note that Java is case-sensitive (even though some versions of MS-Windows are not).

  2. Methods within a class should be listed in alphabetical order (so they are easier to find with the tools typically used by beginning programmers).

    The only exception to this rule is that all constructors must be listed first. For example, in a Queue class, the constructor(s) should be first, the pop method should be second, and the push method should be third.

  3. All variables should be declared at the top of the relevant class or method (with one exception, because it makes them easier to find).

    In other words, class/instance variables should be declared at the top of the class (before any methods are declared) and variables that are local to a method should be declared at the top of that method (before any other lines of code). The only exception to this rule is that index variables in loops may be declared locally.

  4. All variables should be explicitly initialized.
  5. All variables should be declared and initialized in separate statements (to help you understand the difference).

    So, the following is discouraged: 

                 int age = 35;

    and you should, instead, do the following: 

                 int age;

             age = 35;
  6. Class variables (i.e., static attributes) must be declared before instance variables (i.e., non-static attributes).

    Within each category, public variables must be declared first, followed by protected variables, followed by package variables, followed by private variables.

  7. Attributes must be declared before constructors which must be declared before other methods.
  8. All variables should be declared alphabetically by their class/type (because it makes them easier to find).

    For example, variables of type double should be declared before variables of type int which should, in turn, be declared before variables of type Node.

2.2 Names

  1. Class names must start with an uppercase letter.

    In addition, each "word" within a class name should start with an uppercase letter. For example, TextMessage and SimpleTrafficMonitor are both appropriate class names.

  2. The names of "constants" (i.e., static final attributes) and local final variables must be in all uppercase.

    Further, "words" within a "constant" name must be delimited by an underscore character. For example, EXTREMELY_UNHEALTHY is an appropriate name for a "constant".

  3. Other variable and method names that contain multiple characters must not start with an uppercase letter.

    Further, each "word" within a variable name should start with an uppercase letter. For example, importantMessage and campusMonitor are both appropriate variable names.

  4. Variable names that consist of a single character may be uppercase.

    In general, even single-character variable names should be lowercase. However, in some situations, mathematical notation uses uppercase letters. In such situations, uppercase variable names may be used. For example, matrices are often written using uppercase letters. So, an expression like (b = A*x) would be appropriate.

  5. Variable and method/function names must be descriptive.

    Variable names like aaa are not appropriate. Index variables and counters can, however, have names like i and j.

2.3 Declarations

  1. Visibility modifiers (other than package) must be explicit.

    Do not rely on default visibilities.

  2. Modifiers must appear in the following order: public, protected, private, abstract, static, final .
  3. All (non-final) attributes should have private visibility.

    Indeed, they must have private visibility unless there is a very good reason for them not to.

2.4 Comments

  1. Each class must have a descriptive block comment.

    This comment must describe the complete class (rather than the methods in the class), must be in javadoc format, and must include: an @author element (containing your full name), an @version element (containing the date or a version number), and the line This work complies with the JMU Honor Code..

  2. Each method/function must have a descriptive block comment.

    This comment must describe the method, must be in javadoc format, and must include an @param element for each formal parameter and an @return element if the method is not void. These comments must be in the order they are listed and must not be empty.

  3. Comments in the body of a class should use // rather than /* ... */ .
  4. Block comments must be indented at the same level as the surrounding code.

2.5 White Space

  1. Unary operators must not be separated from their operands by any white space.
  2. There must be an empty line after headers, imports, fields/attributes, constructors, and methods.
  3. There must not be a space after a ( or before a ).
  4. A line must not wrap at an operator.

    Instead, the operator must appear on a new line.

  5. A separator (e.g., a comma) must not start a new line.

2.6 Indentation and Blocks

  1. Four spaces must be used for each indentation level.

    Except for array initializations, which must be indented 8 spaces. Also, tabs characters must not be used.

  2. The { must appear at the end of the line containing conditional and loop structures.
  3. The { must appear at the end of the line containing conditional and loop structures.
  4. The } must appear at the start of a new line (because it makes it easy to identify the end of a block). The else {, if there is one, must appear on the same line (after a space).
  5. Code must not contain empty blocks or empty statements.

2.7 Intelligibility

  1. Lines must be short (i.e., less than 80 characters) (so that you can see a complete line even on a low-resolution display).
  2. Files must be short (i.e., less than 2000 lines) (to ensure that they are cohesive).
  3. There must be no more than one statement per line.
  4. Inline conditionals must not be used.
  5. switch statements should have a default clause.
  6. The default clause must be after all case clauses in a switch statement.
  7. case clauses in switch statements should not fall-through
  8. Actual parameters must not be assigned values.
  9. A single method must have no more than two return statements.
  10. Complicated Boolean return statements must be avoided.
  11. Boolean expressions must be simplified.
  12. Block statements (i.e., statements within a {}) must only be used with if statements and loops.
  13. Subexpressions must not contain assignments.
  14. Methods must not be longer than 150 lines (long methods should almost always be broken up into multiple smaller methods, each with a well-defined purpose).

2.8 Reliability and Robustness

  1. Local variables and (most) parameters should not shadow class attributes.

    Parameters in constructors and setters may.

  2. String literals must not be used with the == or != operators.
  3. for loop control variables must not be changed within the body of the loop.
  4. A class must not contain redundant imports.
  5. A class must not contain unused imports.
  6. long literals must use an uppercase L (because the lowercase l is difficult to distinguish from a 1).
  7. In general, static imports statements must not be used.

    They may be used with JUnit packages.

  8. Files must not contain tab characters (because they are interpreted differently on different platforms). Note that most editors can be configured to replace tabs with spaces.

3 Style Humor

Different people have different opinions about what is "stylish". This leads to many fights (and some jokes).

../lectures/comics/Hackles-Style.png
(Courtesy of Hackles)

http://imgs.xkcd.com/comics/code_quality.png
(Courtesy of xkcd)

http://imgs.xkcd.com/comics/code_quality_2.png
(Courtesy of xkcd)

Department of Computer Science

Copyright 2022